                        HELL'S BBS SCRIPT LANGUAGE

CONTENT:

1) INTRODUCTION
2) COMMANDS
3) FUNCTIONS
4) EXAMPLES
5) PREDEFINED VARS
6) EBNF




--------------------------------------------------------------------------
1)
INTRODUCTION:
-------------

For all freaks: There is some kind of EBNF at the end of this file...

Attention: This script-language is just intended to allow people to make
some additional BBS functions. It is VERY slow, due to the fact it was
written 100% in GfA-basic. But on the other side, it offers some stuff
you have NEVER seen in any other programming language.

1. No difference between numbers and strings. -> Calculate with strings!
2. You can CALCULATE a string. The string may even contain script-vars!!
3. Commands to to handle all modem in/output, files/mail/boards...

Possible examples for scripts:

- Alternative connect-sequence to detect fax/voice
- Make list of best up/downloaders
- vote about something
- setup of different user classes with level/quota/areas...
- little games..
- Much more... just use your imagination...

--------------------------------------------------------------------------
2)
COMMANDS:
---------

Syntax: COMMAND [var] [,var]


SET varname,var		[Puts anything into varname
varname=var		[Is exactly the same as SET
set var,"text"		[Put "text" into var. I prefer var="text"
var="anytext"		[Content of var is a text ("anytext")
var="x^2+y^2"		[Content of var is an expression (same as text)
var=x^2+y^2		[Content of var is the result of the expression

PRINT var [,var] 	[Displays data to the screen, with [cr][lf] at end
SEND var [,var]  	[Displays data to the screen.
PRINT "Your level: ",l  [Example. Output: Your level: 0


INPUT var,varname[,var] [Read string from user. [,maxlength] default 60
INPUT "Your age: ",a,2	[Read input with max. lenth 2 and put result in a

IF (expression) AND|OR (expression)   [Conditional branch
ELSE
ENDIF
IF (a*2<b*3) AND (c=3)	[Example
			[ Go here, if true
ELSE
			[ Go here if false...
ENDIF

REPEAT			[Repeat commands until expression is true
UNTIL expression

WHILE expression	[Repeat commands AS LONG as expression true is
WEND

DO			[Endless loop. EXIT or EXIF statement NEEDED!
LOOP

EXIT			[Leaves a structure immediately. (ALSO IF/ENDIF!)
EXIF expression		[Leaves a structure if expression is true

CALC var,varname	[Calculates an expression->result in varname
CALC "a*2/b",res	[Example, put result of a*2/b into res

CURSORPOS var,var	[Positionates the graphics-cursor at var,var=x,y

SAVECURSOR		[Saves position of the cursor
RESTORECURSOR		[Restores the saved position of the cursor

TEXTCOLOR var		[Sets the color of the text (0-7)
BACKCOLOR var		[Sets the color of the background (0-7)
TEXTSTATUS var		[Sets the type of text. (0-7)

USERFIND var,varname	[Finds the number of a user -> result in varname
USERFIND "NAME",number  [Example

GETUSER1 var [,var]	[Gets name and [number] of the first user
GETNUSER var [,var]	[Gets name and [number] of the next user

USERGET var,var,varname [Gets any entry in the user-file
USERGET "SYSOP","LEVEL",lev	[Example... Reads the entry "LEVEL"
 [from the user-file of SYSOP and puts it into lev. You can use the
 [user-number instead of the name to speed up the operation.

USERSET var,var,var     [Same as USERGET, but SETS the entry!

FILEPRINT var		[Prints the (ansi) file var to the screen
%var			[Same, for use in MENUS.BBS file...

FILEPAGE var		[Displays a text-file var in pages!
$var			[Same, for use in MENUS.BBS

PATH var		[Sets the file-path var
>var			[Same, for use in MENUS.BBS

INC varname		[Increments var by 1
DEC varname		[Decrements var by 1

COMMAND var [,var]	[Executes internal functions, defined by numbers
			[See MENUS.BBS for examples

INTERNAL var		[Executes a command-line like in MENUS.BBS
			
LOGIN			[Executes the login routine. Only for LOGIN.SCR

PAUSE var		[Simply pauses var/50 seconds.

SCAN varname		[Scans keyboard for input [ max 1 char in var
LOCALSCAN varname	[Scan ONLY local keyboard at BBS! max 1 char
REMOTESCAN varname	[Scan ONLY remote keyboard! max 1000 chars!!

CODE var,varname	[Encodes a password var [ result in varname

CLS			[Clears the screen

MAIL var,var,var[,var]  [Send a private mail
MAIL "from","to","text","subject"  [Example

EXEC var,var,var	[Execute a TOS binary program
EXEC "file","com","env" [Example

WRITEFILE var,varname	[Put the content of varname into file var
WRITEFILE "file",data   [Example
READFILE var,varname	[Read file var into varname
READFILE "file",var	[Example

MIDSET varname,var,var  [Puts string into var at special position
MIDSET a,pos,"anything" [Example

KILLBUFF		[Erases the input-buffer

UNIXMAIL var		[Includes a unix mail-file, also newsgroups!

KILL var		[Erases a file

TERMINATE		[The BBS program just terminates!!
REBOOT			[Makes the computer reboot! (reset)

HANGUP			[Breaks the line and updates the user

UPDATEUSER		[Updates all informations of the actual user

ECHO ON|OFF|HIDDEN	[Change input display normal/none/as stars

LOCALECHO ON|OFF|ONLY	[Change local echo of BBS

CARRCHECK ON|OFF	[Toggle general carrier-check

--------------------------------------------------------------------------
3)
FUNCTIONS:
----------

A function always returns a value, so put it in a var: ret=FUNCTION(var)

DECIDE(var)		[Execute question in TEXTS.BBS (number var)
CALC(var)		[Calculate any expression, even vars in strings!
UPPER(var)		[Upper cases of any text
LEFT(var,var)		[Left part of var LEFT(var,len)
RIGHT(var,var)		[Right part of var LEFT(var,len)
MID(var,var,var)	[Special part of var MID(var,start,len)
JOIN(var,var [,var])	[Join different vars, treat them as strings!
TEXT(var)		[Return text defined in TEXTS.BBS (number var)
CHR(var)		[Return char of ASCII value
ASC(var)		[Return ASCII valueof first char
LEN(var)		[Return lenght of var
SPACE(var)		[Return a space-string of lenght var
STRING(var,var)		[STRING(len,char) string of char with lenght len
RANDOM(var)		[Return random number between 0 and var-1
EXIST(var)		[Check existence of file. -1=exists 0=not found
SIN(var) COS(var) TAN(var) SQR(var) ....	[Various math. functions

--------------------------------------------------------------------------
4)
EXAMPLES:
---------

4.1) Maths
----------

input "enter a function f(x,y) a.e sqr(x^2+y^2): ",func,20
input "enter x: ",x
input "enter y: ",y
print "Result: ",calc(func)

4.2) Example login script
-------------------------

fileprint "login.ans"

print
print "News: blablabla"

login			[Execute login routine!

mfile="lanliker"

path infopath
if exist(mfile)=-1
 unixmail mfile 	[Include unix-mailfile if present
 kill mfile		[Erase it then....
endif

command 1		[ check for new mail... (System-command number 1)

4.3) An example terminal
------------------------

cls
localecho only			[Do not send to modem
print "Just type ### to quit"
carrcheck off                   [Send without carrier-check
rb="   "
do
	localscan lk		[Scan local keyboard
	if lk<>""		[If input present
		localecho off	[Send to modem, but not to screen!
		send lk		
		localecho only
		rb=lk+left(rb,2) [Check for escape sequence...
	endif
	exif rb="###"		[Leave after escape sequence
	do
		remotescan rk	[Try to read data from the modem
		exif rk=""	[as long we can...
		send rk		[print to screen (localecho only)
	loop
loop
localecho on
carrcheck on

--------------------------------------------------------------------------
5)
PREDEFINED VARS:
----------------

Some vars you can read, but should not set:
This list is not complete, additional vars will follow...

LASTDATE	->Date of previous login of user
LASTTIME	->Time on LASTDATE of previous login of user
ACALL		->Number of calls from user
USER		->Name of actual user
TIME		->Actual time
DATE		->Actual date
TIMER		->200Hz timer
MAINPATH	->Path of actual language-folder
INFOPATH	->Path of start-system-files
HELLDRIVE	->Driver where all BBS-system-data is
CARRIER		->If carrier is present: 1 else 0


--------------------------------------------------------------------------
6)
EBNF:
-----

SOME KIND OF EBNF FOR THE PEOPLE WHO NEED IT (OR THINK THEY NEED IT) :
If you find any mistake in this EBNF, be proud and go drink a beer!

COMMAND [var] [,var]
                              
var          : varname | string

string       : ( text | expression | function ) [ + string]

expression   : factor ["/" | "*" factor]

factor	     : ( number ["-" | "+" number] ) | "("expression")"

number       : realnumber | var | function | string

function     : functionname"("var [,var]")"

realnumber   : inumber ["." inumber]

inumber      : snumber [snumber]

snumber      : "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

text         : "ANY_CHAR_YOU_CAN_TYPE" [text]                

varname      : text [inumber] ["("expression")"]
functionname : text

--------------------------------------------------------------------------
